﻿/*--------------------------------------------------------------------------------
 * Adaptive Intelligence - Foundation Framework
 * Version 2.10
 * 
 * Parsable Interface Definition
 *      Provides an interface for extended Code DOM objects that may parse text
 * into thier own sub-structure.
 *------------------------------------------------------------------------------*/

/*--------------------------------------------------------------------------------
 * System Imports
 *------------------------------------------------------------------------------*/
using System;
using System.CodeDom;
using System.CodeDom.Compiler;

using Adaptive.Foundation;

namespace Adaptive.Foundation.CodeDom
{
    /// <summary>
    /// Provides an interface for extended Code DOM objects that may parse text
    /// into thier own sub-structure.
    /// </summary>
    public interface IParseable
    {
        /*--------------------------------------------------------------------------------
         * Event Definitions
         *------------------------------------------------------------------------------*/
        #region Event Definitions
        /// <summary>
        /// Occurs before parsing begins.
        /// </summary>
        event EventHandler ParseBegin;
        /// <summary>
        /// Occurs once parsing completes.
        /// </summary>
        event EventHandler ParseEnd;
        /// <summary>
        /// Occurs when an exception is caught during parsing,
        /// </summary>
        event ExceptionEventHandler ParseException;
        #endregion

        /*--------------------------------------------------------------------------------
         * Methods / Functions
         *------------------------------------------------------------------------------*/
        #region Methods / Functions
        /// <summary>
        /// Parses the supplied text into the Code DOM graph.
        /// </summary>
        /// <param name="language">
        /// A <see cref="VisualStudioLanguages"/> enumerated value
        /// indicating the language the <i>contentToParse</i> parameter is 
        /// written in.
        /// </param>
        /// <param name="contentToParse">
        /// The code content to be parsed.
        /// </param>
        /// <returns>
        /// <b>true</b> if the operation is successful; otherwise, returns
        /// <b>false</b>.
        /// </returns>
        bool Parse(VisualStudioLanguages language, string contentToParse);
        /// <summary>
        /// Parses the supplied text into the Code DOM graph.
        /// </summary>
        /// <param name="parserInstance">
        /// An <see cref="ICodeParser"/> instance used to perform parsing tasks.
        /// </param>
        /// <param name="contentToParse">
        /// The code content to be parsed.
        /// </param>
        /// <returns>
        /// <b>true</b> if the operation is successful; otherwise, returns
        /// <b>false</b>.
        /// </returns>
        bool Parse(ICodeParser parserInstance, string contentToParse);
        #endregion
    }
}